Tangoe Telecom SOAP API
> Order
getOrderTypes()
The method returns the available order types. No parameter is required to perform this operation. The structure of the used objects may be observed in the appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrderTypesRequest>
<!--Optional:-->
<inv:all>?</inv:all>
</inv:GetOrderTypesRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrderTypesResponse>
<!--Zero or more repetitions:-->
<inv:orderType>
<inv:id>?</inv:id>
<inv:description>?</inv:description>
</inv:orderType>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:GetOrderTypesResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
- Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- the requested order types could not be retrieved from the database;
- Operation error, if a database error occurs.
getOrderStatuses()
The method returns all available order statuses. No parameter is required to perform this operation. The structure of the used objects may be observed in the appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrderStatusesRequest>
<!--Optional:-->
<inv:all>?</inv:all>
</inv:GetOrderStatusesRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrderStatusesResponse>
<!--Zero or more repetitions:-->
<inv:orderStatus>
<inv:id>?</inv:id>
<inv:description>?</inv:description>
</inv:orderStatus>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:GetOrderStatusesResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
- Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- the requested order statuses could not be retrieved from the database;
- Operation error, if a database error occurs.
getOrder()
The method returns an order item for a given service type ID, inventory number, and order number. The result of the operation is an OrderDetails object. The structure of the used objects may be observed in the appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrderRequest>
<inv:orderNumber>?</inv:orderNumber>
</inv:GetOrderRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrderResponse>
<inv:orderItem>
<!--You may enter the following 18 items in any order-->
<!--Optional:-->
<inv:orderID>?</inv:orderID>
<inv:orderNumber>?</inv:orderNumber>
<!--Optional:-->
<inv:orderTypeID>?</inv:orderTypeID>
<!--Optional:-->
<inv:orderStatusID>?</inv:orderStatusID>
<!--Optional:-->
<inv:vendor>?</inv:vendor>
<inv:serviceTypeID>?</inv:serviceTypeID>
<!--Optional:-->
<inv:deviceTypeID>?</inv:deviceTypeID>
<!--Optional:-->
<inv:shippingLocation>?</inv:shippingLocation>
<!--Optional:-->
<inv:dateCreated>?</inv:dateCreated>
<!--Optional:-->
<inv:dateSubmitted>?</inv:dateSubmitted>
<!--Optional:-->
<inv:dateCompleted>?</inv:dateCompleted>
<!--Optional:-->
<inv:dateDue>?</inv:dateDue>
<!--Optional:-->
<inv:orderAccountNo>?</inv:orderAccountNo>
<!--Optional:-->
<inv:ownerUserId>?</inv:ownerUserId>
<!--Optional:-->
<inv:notes>?</inv:notes>
<!--Optional:-->
<inv:customFields>
<!--Zero or more repetitions:-->
<inv:customField>
<!--Optional:-->
<inv:id>?</inv:id>
<inv:name>?</inv:name>
<inv:value>?</inv:value>
<!--Optional:-->
<inv:fieldType>?</inv:fieldType>
<!--Optional:-->
<inv:required>?</inv:required>
</inv:customField>
</inv:customFields>
<!--Optional:-->
<inv:comments>?</inv:comments>
<inv:inventoryNumbers>
<!--1 or more repetitions:-->
<inv:inventoryNumber>?</inv:inventoryNumber>
</inv:inventoryNumbers>
</inv:orderItem>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:GetOrderResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
- Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- the order could not be found for the provided order number
- Operation error, if a database error occurs.
getOrdersForInventoryItem()
The method returns all available orders for a given service type ID and inventory number. The result is a list of OrderDetails object. The structure of the used objects may be observed in the appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrdersForInventoryItemRequest>
<!--You may enter the following 3 items in any order-->
<inv:serviceTypeID>?</inv:serviceTypeID>
<!--Optional:-->
<inv:deviceTypeID>?</inv:deviceTypeID>
<inv:inventoryNumber>?</inv:inventoryNumber>
</inv:GetOrdersForInventoryItemRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:GetOrdersForInventoryItemResponse>
<!--Zero or more repetitions:-->
<inv:orderItem>
<!--You may enter the following 18 items in any order-->
<!--Optional:-->
<inv:orderID>?</inv:orderID>
<inv:orderNumber>?</inv:orderNumber>
<!--Optional:-->
<inv:orderTypeID>?</inv:orderTypeID>
<!--Optional:-->
<inv:orderStatusID>?</inv:orderStatusID>
<!--Optional:-->
<inv:vendor>?</inv:vendor>
<inv:serviceTypeID>?</inv:serviceTypeID>
<!--Optional:-->
<inv:deviceTypeID>?</inv:deviceTypeID>
<!--Optional:-->
<inv:shippingLocation>?</inv:shippingLocation>
<!--Optional:-->
<inv:dateCreated>?</inv:dateCreated>
<!--Optional:-->
<inv:dateSubmitted>?</inv:dateSubmitted>
<!--Optional:-->
<inv:dateCompleted>?</inv:dateCompleted>
<!--Optional:-->
<inv:dateDue>?</inv:dateDue>
<!--Optional:-->
<inv:orderAccountNo>?</inv:orderAccountNo>
<!--Optional:-->
<inv:ownerUserId>?</inv:ownerUserId>
<!--Optional:-->
<inv:notes>?</inv:notes>
<!--Optional:-->
<inv:customFields>
<!--Zero or more repetitions:-->
<inv:customField>
<!--Optional:-->
<inv:id>?</inv:id>
<inv:name>?</inv:name>
<inv:value>?</inv:value>
<!--Optional:-->
<inv:fieldType>?</inv:fieldType>
<!--Optional:-->
<inv:required>?</inv:required>
</inv:customField>
</inv:customFields>
<!--Optional:-->
<inv:comments>?</inv:comments>
<inv:inventoryNumbers>
<!--1 or more repetitions:-->
<inv:inventoryNumber>?</inv:inventoryNumber>
</inv:inventoryNumbers>
</inv:orderItem>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:GetOrdersForInventoryItemResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- an inventory item could not be found for the provided service type id/device type id and inventory number;
- Operation error, if a database error occurs.
addOrder()
The method adds an inventory order item into the database using the provided fields from OrderDetails object. The result of the operation is an object represented by a code and a message that provides details about the success of the operation. The order is not created if the provided inventory item the order is created for does not exist. The structure of the used objects may be observed in the appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:AddOrderRequest>
<inv:orderItem>
<!--You may enter the following 18 items in any order-->
<!--Optional:-->
<inv:orderID>?</inv:orderID>
<inv:orderNumber>?</inv:orderNumber>
<!--Optional:-->
<inv:orderTypeID>?</inv:orderTypeID>
<!--Optional:-->
<inv:orderStatusID>?</inv:orderStatusID>
<!--Optional:-->
<inv:vendor>?</inv:vendor>
<inv:serviceTypeID>?</inv:serviceTypeID>
<!--Optional:-->
<inv:deviceTypeID>?</inv:deviceTypeID>
<!--Optional:-->
<inv:shippingLocation>?</inv:shippingLocation>
<!--Optional:-->
<inv:dateCreated>?</inv:dateCreated>
<!--Optional:-->
<inv:dateSubmitted>?</inv:dateSubmitted>
<!--Optional:-->
<inv:dateCompleted>?</inv:dateCompleted>
<!--Optional:-->
<inv:dateDue>?</inv:dateDue>
<!--Optional:-->
<inv:orderAccountNo>?</inv:orderAccountNo>
<!--Optional:-->
<inv:ownerUserId>?</inv:ownerUserId>
<!--Optional:-->
<inv:notes>?</inv:notes>
<!--Optional:-->
<inv:customFields>
<!--Zero or more repetitions:-->
<inv:customField>
<!--Optional:-->
<inv:id>?</inv:id>
<inv:name>?</inv:name>
<inv:value>?</inv:value>
<!--Optional:-->
<inv:fieldType>?</inv:fieldType>
<!--Optional:-->
<inv:required>?</inv:required>
</inv:customField>
</inv:customFields>
<!--Optional:-->
<inv:comments>?</inv:comments>
<inv:inventoryNumbers>
<!--1 or more repetitions:-->
<inv:inventoryNumber>?</inv:inventoryNumber>
</inv:inventoryNumbers>
</inv:orderItem>
</inv:AddOrderRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:AddOrderResponse>
<!--Optional:-->
<inv:orderID>?</inv:orderID>
<!--Optional:-->
<inv:inventoryIds>
<!--Zero or more repetitions:-->
<inv:inventoryID>?</inv:inventoryID>
</inv:inventoryIds>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:AddOrderResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
- Inside the provided order item, the following fields must always be provided: serviceTypeID, inventoryNumbers, orderNumber, orderTypeID, vendor;
- It is possible for a service type to have required custom fields, in which case values for these fields must be provided;
- OrderStatusID is always set on the state that designates the open status (this state is indicated by a property in the TIMS.properties file);
- The following elements accept only particular values:
- serviceTypeID – an existing service type ID;
- venodor – and exiting Vendor
- deviceTypeID – and existing Device Type Id
- inventoryNumbers –existing inventory numbers for the provided service type;
- orderNumber – a non existing order number
- orderTypeID – an existing order type ID;
- dateCreated – a mm/dd/yyyy string representation of a valid date;
- dateDue– a mm/dd/yyyy string representation of a valid date;
- shippingAddress – a valid location no.
- ownerUserId – an existing Tims User ID
- DateCompleted is ignored as the status is always set on the state that designates the open status;
- If the value of a custom field of boolean type is not provided, it will default to false;
- If the value of a custom field of integer type is not provided, it will default to zero (0);
- If the value of a custom field of double type is not provided, it will default to zero (0);
- The user that is associated with this operation must be set in the TIMS.properties file.
Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- the user id from the properties file was not set correctly;
- orderNumber contains one of the following characters “, %, ‘, `, \ or spaces, tabs or line brakes;
- there is already an order with the provided orderNumber (the order number is unique).
- at least one of orderTypeID, dateCreated is not provided (as they are considered compulsory).
- At least one of the inventoryNumbers provided do not have the same Vendor and Service Type as the ones provided for the order creation.
- one of the particular fields (vendor, shippingAddress, serviceTypeID, inventoryNumbers) contains invalid data;
- one of the particular fields enumerated above contains invalid data;
- a custom field contains an invalid value – an option that does not exist for combo type one, a string represented different from mm/dd/yyyy for a date one, a string that does not represent an integer for an integer one, a string that does not represent a double for a double one, a string different from 0 or 1 for a Boolean one;
- a custom field that is required for the provided service type is not provided;
- a custom field does not exist among those of the category the new order is added;
- Operation error, if a database error occurs.
editOrder()
The method updates the order with the data provided in the OrderDetails object. The result of the operation is an object represented by a code and a message that provides details about the success of the operation. The structure of the used objects may be observed in appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:EditOrderRequest>
<inv:orderItem>
<!--You may enter the following 12 items in any order-->
<inv:orderNumber>?</inv:orderNumber>
<!--Optional:-->
<inv:orderTypeID>?</inv:orderTypeID>
<!--Optional:-->
<inv:orderStatusID>?</inv:orderStatusID>
<!--Optional:-->
<inv:dateDue>?</inv:dateDue>
<!--Optional:-->
<inv:dateSubmitted>?</inv:dateSubmitted>
<!--Optional:-->
<inv:dateCompleted>?</inv:dateCompleted>
<!--Optional:-->
<inv:customFields>
<!--Zero or more repetitions:-->
<inv:customField>
<!--Optional:-->
<inv:id>?</inv:id>
<inv:name>?</inv:name>
<inv:value>?</inv:value>
<!--Optional:-->
<inv:fieldType>?</inv:fieldType>
<!--Optional:-->
<inv:required>?</inv:required>
</inv:customField>
</inv:customFields>
<!--Optional:-->
<inv:comments>?</inv:comments>
<!--Optional:-->
<inv:shippingLocation>?</inv:shippingLocation>
<!--Optional:-->
<inv:orderAccountNo>?</inv:orderAccountNo>
<!--Optional:-->
<inv:ownerUserId>?</inv:ownerUserId>
<!--Optional:-->
<inv:notes>?</inv:notes>
</inv:orderItem>
</inv:EditOrderRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:EditOrderResponse>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:EditOrderResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
- The order that is edited is determined based on the provided orderNumber;
- Inside the provided order item, the following fields must always be provided: inventoryNumbers, orderNumber;
- DateCreated cannot be edited;
- An order whose status closed (or one that represents this status) cannot be edited;
- The following elements accept only particular values:
- inventoryNumbers – existing inventory numbers that have the same vendor and service type as the order
- orderNumber – an existing order number
- orderTypeID – an existing order type ID;
- dateDue– a mm/dd/yyyy string representation of a valid date;
- dateCompleted– a mm/dd/yyyy string representation of a valid date;
- shippingAddress – a valid location no.
- ownerUserId – an existing Tims User ID
- DateCompleted is set only if the provided status is the closed one (or one that represents this status). It is set with the provided value if one is provided or with the current date of execution otherwise;
- Service type ID, order number, vendor of an item cannot be edited;
- The value of a boolean custom field is specified as 0 (false) or 1 (true);
- The user that is associated with this operation must be set in the TIMS.properties file;
- If the provided status is the closed one (or one that represents this status), the order will be set as resolved by the user associated with this operation.
Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- the user id from the properties file was not set correctly;
- the open and closed statuses from the properties file were not set correctly;
- one of the particular fields enumerated above contains invalid data;
- a custom field contains an invalid value – an option that does not exist for combo type one, a string represented different from mm/dd/yyyy for a date one, a string that does not represent an integer for an integer one, a string that does not represent a double for a double one, a string different from 0 or 1 for a Boolean one;
- a custom field does not exist among those of the category the new order is added;
- Operation error, if a database error occurs.
21.1 Changes:
- logic was added regarding the notes field presence as part of the request message
The notes attribute is handled differently depending on its presence and value inside the request message:
- if the field is not part of the payload, the value of the order field is left as it has been
- if the field is part of the payload and has non empty value, the value of the order field is changed to the new value
- if the field is part of the payload and has an empty value, the value of the order field is erased
addItemsToOrder()
The method adds exiting inventory items to an existing order. The result of the operation is an object represented by a list of the added inventory ids, a code and a message that provides details about the success of the operation. The structure of the used objects may be observed in appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:AddItemsToOrderRequest>
<inv:orderNumber>?</inv:orderNumber>
<inv:inventoryNumbers>
<!--1 or more repetitions:-->
<inv:inventoryNumber>?</inv:inventoryNumber>
</inv:inventoryNumbers>
</inv:AddItemsToOrderRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:AddItemsToOrderResponse>
<!--Optional:-->
<inv:inventoryIds>
<!--Zero or more repetitions:-->
<inv:inventoryID>?</inv:inventoryID>
</inv:inventoryIds>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:AddItemsToOrderResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
- The order to which items will be added is determined based on the provided orderNumber;
- Inside the provided order item, the following fields must always be provided: inventoryNumbers;
- Items cannot be added to an order whose status closed (or one that represents this status);
- The following elements accept only particular values:
- inventoryNumbers – existing inventory numbers that have the same vendor and service type as the order
- orderNumber – an existing order number
Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- the user id from the properties file was not set correctly;
- the open and closed statuses from the properties file were not set correctly;
- one of the particular fields enumerated above contains invalid data;
- Operation error, if a database error occurs.
removeItemsFromOrder()
The method removes assigned inventory items from an existing order. The result of the operation is an object represented by a code and a message that provides details about the success of the operation. The structure of the used objects may be observed in appendix section of this document. The format of the request and response messages is the following:
Request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:RemoveItemsFromOrderRequest>
<inv:orderNumber>?</inv:orderNumber>
<inv:inventoryNumbers>
<!--1 or more repetitions:-->
<inv:inventoryNumber>?</inv:inventoryNumber>
</inv:inventoryNumbers>
</inv:RemoveItemsFromOrderRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://www.asentinel.com/asentinelws/schemas/invord">
<soapenv:Header/>
<soapenv:Body>
<inv:RemoveItemsFromOrderResponse>
<inv:result>
<!--You may enter the following 2 items in any order-->
<inv:code>?</inv:code>
<!--Optional:-->
<inv:message>?</inv:message>
</inv:result>
</inv:RemoveItemsFromOrderResponse>
</soapenv:Body>
</soapenv:Envelope>
Notes:
- The order from which items will be removed is determined based on the provided orderNumber;
- Inside the provided request, the following fields must always be provided: inventoryNumbers;
- Items cannot be removed from an order whose status closed (or one that represents this status);
- The following elements accept only particular values:
- inventoryNumbers – existing inventory numbers that have the same vendor and service type as the order
- orderNumber – an existing order number
Errors:
- Message validation error - SOAP fault message (see dedicated section for more details);
- Data validation error – situations:
- the user id from the properties file was not set correctly;
- the open and closed statuses from the properties file were not set correctly;
- one of the particular fields enumerated above contains invalid data;
- the order that is edited has is the closed status;
- the request tries to remove all items assigned to the order. An order must have at least one item assigned to it.
- Operation error, if a database error occurs.